Cream of the Crop 22

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 22 / Cream of the Crop 22.iso / database / eb108.zip / PACK1.PRG / EBOUT / EB5.REP < prev next >

Wrap

Text File | 1996-11-10 | 40KB | 1,109 lines

═══════════════════════════════════════════════════ EASY BASE NETWORKING GUIDE Contents ─────────────────────────────────────────────────── Introduction Page 1 Batch Starting Page 3 Clearing Locks Page 4 Configuration Page 6 Development Work Page 7 File Open On Server Page 9 Lock Directory Page 10 Numbering Records Page 11 Private Keyword Page 12 Protective Locking Page 13 Self Locking Loops Page 16 Strategic Locking Page 17 Terminal Number Val. Page 18 Unique Entries Page 19 ................................................................................ Introduction Introduction Easy Base Networker has been designed to make the creation of multi user data management systems as simple as possible. To do this it incorporates automatic locking and privatisation routines. With a few exceptions, you can create multi user systems just as if you were writing for a stand alone PC. The few exceptions are, however, important so please read this short guide before attempting to convert any single user application. Because Easy Base is an interpreter, the same program is used both for the creation of your application and for running it. Only the running routines are multi user. Multiple work stations can access the same forms and procedures simultaneously only when such forms and procedures are called from pre defined user menus. Multiple work stations can access the form and procedure design routines (System Menus) provided they are each doing design work in different data sub directories. No two work stations can access the system menus for the same data sub directory at the same time. Terminology used in this Guide. PUBLIC FILES: Files to which all work stations have access. The public files are form definition, data and procedure definition files together with the network common configuration file. PRIVATE FILES: Files for which each work station has its own copy. The private files are: user menus, terminal configuration, procedure output subindex and temporary forms. You can also write to private copies of public form definitions for temporary storage by using the keyword "Private". TERMINAL NUMBER:- This is a unique number assigned to each work station logged on to Easy Base. The terminal number is used in the naming of the work station's private files and for recording which work station has placed any access lock. SYSTEM LOCKS The locks which Easy Base engages to prevent simultaneous loading and simultaneous access to the system menus in any one data sub directory. PROTECIVE LOCKS The locks which Easy Base engages to prevent index file - 1 - ................................................................................ Introduction Introduction corruption during multiple access. STRATEGIC LOCKS The locks you set in procedure code when you require a form to be locked for non protective reasons. Easy Base Networker was developed under Novell Personal Netware. It does not, however, contain any Novell specific code and should be reliable on any DOS based network system. To get started, install Easy Base to a new directory on a server. Allocate a drive letter for your work stations to reference this directory and set your network software to allow unrestricted read and write access to all files in that directory and all sub directories under it. To log on to Easy Base, three parameters are required. The terminal number to use, The data sub directory to operate in and a password for either the system menus or a user menu. From a work station, change to the drive you have allocated and type "EB". When you start Easy Base with the command EB you will be asked to supply the three parameters which it requires. All three parameters can be supplied automatically either by setting them in the environment ( Work stations which self boot ) or by placing them on the command line. ( See Batch Starting ) All locking in Easy Base is by "Soft lock". DOS file and record locking techniques are not used. With any locking strategy, locks can be left engaged if a work station suffers a power failure or is switched off without exiting the program. System and Access locks which are left engaged after a power failure can be cleared by Easy Base or by DOS file erasure. (See Clearing Locks ) Applications written in previous stand alone versions of Easy Base can be copied directly to a sub directory of Easy Base Networker. However, the pre processed (.PPR) files created by Version 9 are NOT compatible with Network V1 and must be erased before use. You can erase all .PPR files by selecting Relationships from the main system menu. The system values Total Records, Total Copies and Current Record no longer exist. Any procedure which uses these values must be changed. They are now available as pseudo fields Form.Total Records, Form.Total Copies and Form.Record Number. - 2 - ................................................................................ Batch Starting Batch Starting You can by pass entering any or all of the sign on parameters either by setting them in the environment of the work station or by supplying them on the command line. To have a work station automatically log on as terminal 1 in the sub directory accounts with the password "Fred", add the following lines to the work station's Autoexec.Bat file:- SET EBT=1 SET EBD=ACCOUNTS SET EBP=FRED Or start Easy Base with the command line :- EB T=1 D=ACCOUNTS P=FRED Any parameters which are not supplied either in the environment or on the command line will be asked for on start up. If you have set the start up parameters for any given work station in the environment and you start Easy Base with different parameters on the command line, the parameters on the command line override those in the environment. If your application has different passwords for different menu structures you can set the terminal number and directory and leave the user to supply the password. If the user has access to different directories then just set the terminal number and the user can choose the directory and enter the password. NOVELL WARNING ══════════════ If you save a "Login Script" after setting EB environment variables and subsequently change the settings in your Autoexec.bat file, Novell will swap the setting it saved for the new ones whenever you login. Saving a new Login script after the change does not rectify the situation. You actually have to find the login script file and edit out the old environment settings. Under Novell Personal Netware this file is called PNWLOGIN.SCR and is stored in a numbered sub directory under C:\NWCNTL\MAIL - 3 - ................................................................................ Clearing Locks Clearing Locks ACCESS LOCKS If a data access lock is left engaged it can be cleared by selecting "Clear Access Locks" from the utilities menu. You can also make "Clear Access Locks" available on user menus. When you run "Clear Access Locks" Easy Base clears all access locks in the current data sub directory. Because it clears ALL locks in the current directory you should ensure that no other work stations currently require locks in place - ie they should not be running procedures or adding or modifying records. There is no need for them to log out of Easy Base. SYSTEM LOCKS Easy Base uses two system locks - a loading lock and a System Menus lock. Because of the way Easy Base initially loads its overlays, no two work stations can load at the same time. When a work station attempts to load Easy Base while another work station is loading, Easy Base displays the message "Please wait another terminal is loading". As soon as the first work station has logged on this message will clear and the second will load. If the first terminal suffers a power failure while loading, this lock will be left engaged. If the loading lock does not clear within one minute, The "Please wait" message displayed on any other work station which is trying to load is replaced with one which allows the user to escape and enter the reset command. To clear the loading lock type "EB reset" at the command prompt. Whenever a work station is accessing the system menus for any given data sub directory, all other terminals are locked out of the system menus in that directory. If a work station is powered off without leaving the system menus then this lock will be left engaged and no work station will be able to access the system menus for that directory. The system menu lock is also cleared by typing "EB reset" at the command prompt. WARNING It is essential to your data integrity that no two work stations log in to Easy Base with the same terminal number. To prevent this Easy Base maintains a log of which terminal numbers are in use. This log is erased when you issue the command "EB reset". If one or more terminals are logged on to Easy Base and another issues the command "EB reset" then it will be able to log on with a terminal number which is already in use. You must prevent this as the two work stations with the - 4 - ................................................................................ Clearing Locks Clearing Locks same terminal number will overwrite each others private files and ignore each others data access locks with unpredictable results. If you have arranged for each work station to supply its parameters from the environment or from the command line in a batch start this is not a problem, but if you allow work station operators to choose their terminal number it is. To be absolutely sure, you should ensure that all work stations exit Easy Base before issuing the "EB Reset" command and log back in after it. DOS LOCK CLEARING All Easy Base locks can be cleared manually by erasing the locking files. The locking files are:- Loading Lock EB.LOD Easy Base Directory System Menus Lock EB.LOG Easy Base Directory Directory Lock DIR.LOC Data Directories Form Locks Base(No).LOC Data Directories - 5 - ................................................................................ Configuration Configuration The utilities Install Printer, Options, Screen Colours and Set Paper Length described in the programmers reference are combined under "Configuration" on the main menu in the network version of Easy Base. You can also add configuration to a user menu. Apart from date and numeric formatting, all configuration items are private to the terminal being configured. You can therefore install different printers on different workstations. When you install a printer in Easy Base you only have the option to send output to LPT1 or LPT2. When you select an LPT port the output will be sent either to a printer connected to that port or to a network printer that has been mapped to it by your network software. CAUTION: Novell netware reports three LPT ports on all workstations even if they only physically have one. If you set output to LPT2 and your workstation has no physical LPT2 and no network printer has been mapped to LPT2 then Easy Base will hang up when you try to print. When you change the network common items, date and numeric format. They only take effect on other workstations from the next time they log in. - 6 - ................................................................................ Development Work Development Work When you are doing development work from the system menus there should not be any other operator accessing forms or procedures in the data directory you are working in. This does not mean that you cannot have a second workstation accessing that directory under your control. It is in fact preferable to have a second workstation for testing purposes. There are aspects of design work that Easy Base does not and in some cases cannot provide locking for. This section will explain how to avoid conflicts. The only system operations which are fully protected are Data entry from the system menus and packing forms. You can perform these operations safely even when other operators are active. Whatever system operation you perform, there will be no conflict if the other active workstation/s are at rest displaying a user menu. To make and test modifications to an application, provide access to the system menus from your user menu and start your application on the user menu for both workstations. One workstation can then access the system menus while the other remains on the user menu. After modifying a form or procedure you can then escape to the user menu and test the modification in a multi user environment. Modifications to forms, relationships and procedures are effective immediately. Modifications to User Menus, Vat rates and network common configuration items take effect the next time a workstation logs on or changes directory. If, for example, you change your user menu structure then you must select Change data directory and select the same directory again before it is displayed. If your application is in constant use, you can minimize down time by making and testing your modifications in a spare directory with a copy of the App. Once you are happy, other users only have to be shut down while you make the modifications in the live directory and not while you do your testing. If you absolutely have to make modifications without shutting down other workstations then there is only one operation which can actually corrupt your data. That is if you modify a form such that its record length changes. You MUST NOT do this while any other workstation is in data entry to that form or is running a procedure which updates that form. The other work station will continue using the old record length and corrupt the data file. All other operations may or may not cause - 7 - ................................................................................ Development Work Development Work spurious system errors on either your workstation or one of the others but will not normally affect data. Whenever you add modify or delete forms, procedures, relationships, choice lists or user menus Easy Base erases and re writes the definition file and the form, procedure or choice list directory file. Any workstation which attempts to read from a file between the erase and re write will crash, and your workstation will crash if it actions the erase while another workstation has the file open. - 8 - ................................................................................ File Open on Server File Open on Server If a workstation fails and it had files open at the time, then your network server will prevent any other workstation from erasing those files before the failed workstation logs back in to the network. There are several processes in Easy Base which erase files. These are, packing, the procedure commands "clear records from" and "rename temp as" as well as form, relationship and procedure modifications from the system menus. If any workstation suffers a power failure while accessing Easy Base you should re start it and log back on to the network as soon as possible. If the failed workstation did not have files open at the time of the failure then other workstations will continue to work normally. If it did have files open then any workstation which tries to erase one of those files will crash with a "File Open on Server" message. Any such errors will cease as soon as the failed workstation logs back on to the network. If the failure was such that the failed workstation cannot be restarted then you must shut down and restart the server. During most activity in Easy Base, it is unlikely that a workstation failure will cause problems. There is one major exception to this. That is if a workstation fails while packing a form. If a workstation fails while packing a form, Easy Base will restart the packing process automatically the first time any workstation logs on to that data directory. If the failed workstation has not logged back in to the network then any other workstation logging on to the data directory will crash with the "File Open on Server" message. In other words, no workstation will be able to access the data directory until either the failed workstation is back on the network or the network server has been restarted. You may also get a "File Open on Server" error if any other program such as a fileviewer opens an Easy Base file. - 9 - ................................................................................ Lock Directory Lock Directory When you need to make modifications to an application you can prevent other workstations from logging on to the directory you are about to modify by selecting "Lock Directory" from the utilities menu. If any other workstations are active in the directory when you select Lock Directory, Easy Base will list their terminal numbers on screen. When all other workstations have logged out of the directory the lock will engage. When you have finished your modifications select "Clear Access Locks" to clear the directory lock. Apart from application modifications, the directory lock should be used before backup, restore or data import routines. Once a directory lock has been set, only a workstation using the terminal number which set it can access the directory. - 10 - ................................................................................ Numbering Records Numbering Records If you are converting a single user application then you may have to adjust your code where records are entered via a procedure and each record has to have a consecutive number in one of its fields. In single user applications record numbering is often done by having a "Last" form which holds a single record with the last record number in it. The procedure which enters new records derives the next record number in a field on its input screen with the derivation :- Lookup(Last,Number) + 1 and the procedure code updates the last form :- For Last Last.number = input.number Update record Next In a multi user environment this is not reliable. If another workstation starts the procedure after yours has done the lookup but before you run the procedure then both workstations will derive the same number on screen. To ensure correct numbering your procedure code must re-check the Last.number value when it is run. For Last input.number = last.number + 1 Last.number = input.number Update record next Although this will ensure correct numbering, it may be off putting to see the same record number on two screens. To avoid this you can declare a variable to pick up the number in and delete the input.number field. The code would then be:- Declare variables number as number end for last number = last.number + 1 Last.number = number Update record next For form new record form.number = number copy all from input next - 11 - ................................................................................ Private Keyword Private Keyword One of the main differences between stand alone and multi user applications is that where a form is used for temporary storage each workstations temporary records must be kept separately. For example, in an order taking application you might have one procedure which looks up stock items and enters them to an "OrderItems" form. When all the items have been entered another procedure prints out the order and clears down the "OrderItems" form. If these procedures are to be used by more than one work station then, clearly, the items entered by one station must be stored separately from those entered by another. In many data management systems this would involve separate forms and procedures for each work station. In Easy Base you can separate data by placing the keyword "Private" at the end of any for loop and at the end of the "clear records from" command. In this example the following procedures can be used by any number of work stations to create separate orders using the same procedures and OrderItems form. For OrderItems new record private Copy all from input Next ......................................... For OrderItems private Total = Total + orderitems.price print list items next Print report footer ......................................... Clear records from OrderItems private As an aid to debugging you can view the records which have been entered privately for any workstation by pressing Ctrl + P when in data entry to the form. CAUTION The provision of private data files is for temporary storage in applications like the one described above. It is not suitable for keeping permanent private records. There are no facilities for packing or reformatting the private data file. Private records can only be removed with the "Clear records from form private" command in procedure code. If you modify a form which has private data records the private data is not reformatted to the new form definition and the old data must be erased with the "Clear records from" command before use. - 12 - ................................................................................ Protective Locking Protective Locking The Easy Base protective locking allows any number of work stations to read or write to data files simultaneously where no index file is involved. It allows any number of workstations to read via the same index file simultaneously but prevents any workstation from writing to an index file that is being read from. It prevents simultaneous writing to the same index file and any file from being erased while in use. Whenever a workstation attempts a process that is locked by another work station Easy Base waits for the lock to be released. If the lock is not released within four seconds Easy Base displays the message "Waiting for Access - Esc Cancel". If the user presses the escape key with this message on screen, the process is cancelled. If the process was in data entry to a form the workstation remains in data entry to that form and is ready to accept any other input. If the process was during a procedure then the procedure is terminated. If it had a repeating input screen, control returns to the input screen and if it did not, control returns to the menu from which it was called. The protective locking routines in Easy Base are automatic apart from two options. 1. In certain procedures you will not wish to allow the user the option to cancel the procedure when he has to wait for a lock to clear. To do this, place the command "Wait" in the procedure code after output field and variable declarations. If the command "Wait" has been issued and the procedure encounters a lock which lasts more than four seconds then Easy Base still displays the message "Waiting for Access" but the escape key is not active. 2. Easy Base provides two options for locking while a procedure reads records using an index file. Consider the code:- For Customers with Surname in order Print list items next For this procedure to complete successfully, no other work station must write to the index file on Surname during the procedure. If there are many records in the customers file and the output is being sent to a printer then other workstations could be prevented from adding modifying or deleting records in the customers form for some considerable time. As well as reading directly from the Customers.Surname index Easy Base can also make a private copy of the index file as it stands at the start of the procedure. The Customers form is locked only for as long as it takes to make the copy. Once the - 13 - ................................................................................ Protective Locking Protective Locking file has been copied, other workstations are free to write to the customers form and the procedure selects records using its private copy of the index file. By default, Easy Base locks the form against write processes during the procedure. To take the private index option add the command "No Lock" to the end of the "For" line. For Customers with surname in order no lock There are pros and cons for both methods and the exact nature of your application will determine which should be used in any given for loop. The default system prevents writing to the form for the duration of the loop but has no anomalies in the output. The copy index method locks the form for the minimum time, but if the indexed field of any record is altered by another workstation the altered record may be processed out of order. For example, in this loop, if another workstation changes a customers surname from Smith to Jones before the procedure reaches the Smiths, you will have a Jones listed among the Smiths in your printout because that is the record's position in the private index. The "No Lock" option should only be applied to for loops of public files. It should not be applied to any loop which is already private. :- PickList, Temp, any loop using the private keyword and any loop using a subindex are automatically private. EASY BASE AUTOMATIC LOCKING SUMMARY File Erasure (Packing, Clear records from, Rename temp as) :- None of these processes will start while any other workstation is accessing the form to which they apply. Once they have started, no other workstation can access the form until they are complete. Data Entry to forms :- File erasure is not permitted at any stage. Write locking is engaged during an F3 search on an indexed field and while any other workstation makes a lookup from one of the forms indexed fields. Read and write locking is engaged during F2 add or update record and during F7 delete record. Procedures :- In procedures, locks are set separately for each "For" loop. - 14 - ................................................................................ Protective Locking Protective Locking When loops are nested, the locks set by each loop are retained until the procedure exits the outermost loop when they are all cleared together. Loops of Picklist, Temp, Subindex and any loop using the private keyword have no locking as the files involved are private to the workstation. Unqualified loops ( For Form ) Lock against file erasure only. Loops qualified by "With" set a write lock on the form. Loops qualified by "New Record" or containing the commands "Update record" or "Delete record" lock the form against read or write. A loop prefixed by "Index Off" follows the same rules as for Packing. It will not start while any other workstation is accessing the form and once started, no other workstation can access the form until it is finished and the indexes are rebuilt. - 15 - ................................................................................ Self Locking Loops Self Locking Loops When For Loops of the same form are nested in a procedure Easy Base ignores any lock which the workstation has set for the outer loop when it starts the nested one. It does not ignore any lock set by another workstation. It is therefor possible to write a procedure which cannot be run on two workstations simultaneously because they will each lock each other. For parts with number = input.number for parts alias addone new record copy all from parts Addone.number = jointext(input.number,"a") next next Although a legitimate procedure in a single user environment, this will self lock if run on two workstations. The first line sets a read only lock on the parts form. A single workstation will ignore its own lock and write the new record but if two workstations run the procedure neither will be able to write the new record until the other releases its read only lock. Such procedures are seldom necessary and when they are you can avoid the problem by making the read only lock the inner one. For parts new record for parts alias getone with number = input.number parts.name = getone.name parts.Qty = getone.Qty parts.number = jointext(input.number,"a") next next Although the convenience of using "Copy all from" has been lost this procedure will not self lock. The outer loop now locks read and write access to the parts form so any other work station attempting to run the same procedure cannot start until this one has finished. - 16 - ................................................................................ Strategic Locking Strategic Locking Strategic locks are locks which are not covered by the automatic protective locking but are none the less necessary for the correct operation of an application. Strategic locks are set by the procedure command Lock and cleared by the command Unlock. Strategic locks will not engage while any other workstation is accessing the form to be locked and once set prevent any other workstation from accessing the form before the Unlock command has been issued. Each Lock command must have a matching Unlock command but they need not necessarily be in the same procedure. If a form has to be locked while several procedures run from a batch menu, for example, then the first procedure can lock the form and the last can unlock it. Strategic locks are seldom required in applications which simply store and report on data. In transactional applications however, they are often essential. As an example, a form "Work" contains records of the hours worked by employees - one record for each time each employee clocks in. Each record also has a number field and procedures which enter records to the form derive the record number field from a form "Last" which contains a single record with the last record number in form "Work". When a single employees records are deleted from the form, the form is packed, the records are renumbered and the entry in the "Last" form is updated with the new number of records in "Work" The Easy Base protective locking will prevent any other work station from entering a new record during the deletion loop and during the pack. It will not prevent it from entering a new record between the deletion loop and the pack or between the pack and the updating of the "Last" form. To ensure that no other workstation adds a new record to work before the "Last" form is updated the "Last" form must be locked throughout. Lock Last For Work with employee = input.employee Delete record Next Pack Work For Last For Work x = x + 1 : Work.number = x Update record Next Last.number = x : Update Record Next Unlock Last - 17 - ................................................................................ Terminal Number Val. Terminal Number Val. The System value "Terminal Number" is available in field derivations and procedure code and returns the terminal number used to log on to Easy Base. The main use of the Terminal Number value is to privatize lookups in temporary storage forms. As an example, an invoicing system might have one procedure which looks up a customers number from the "customers" form and looks up the next invoice number from the "last" form. It then enters a record in the "current" form so that the next procedure, which looks up stock items and enters them privately to the "invoicelines" form, can automatically lookup the "Current.Customer" and "Current.invoice". If multi workstations are to use these procedures at the same time then each must be able to lookup its own Current.Customer and Current.Invoice. To do this, in say a six terminal application, six records are pre entered to the "current" form with the values 1,2,3,4,5 and 6 in the terminal field. The first procedure has the code:- Declare variables No as number end for last No = last.invoiceno + 1 last.invoiceno = No Update record next for current with terminal = terminal number current.customer = input.customer current.invoiceno = no Update record Next The procedure which enters the invoicelines has a hidden field "Terminal" derived :- Terminal Number and looks up the current invoice number and customer based on a relationship linking this field with the terminal field in the "Current" form. The Terminal Number value can also be used to create private entries in public forms. If a public form "Notes" has a field "Terminal" and each workstation enters its notes together with its terminal number then the procedure: For Notes with terminal = terminal number Print list items next Will only print the notes entered by the workstation running the procedure. - 18 - ................................................................................ Unique Entries Unique Entries Where new records are entered to forms via procedures and one of the fields in the form must be unique, the procedure must test to see if the value it is about to enter in the unique field already exists. In single user applications this test can be accomplished solely on the input screen. To check a unique field "Name" in form Parts the input screen name field would be derived:- If(lookup(parts,name) = name,blank[beepPart Name Exists !Cursor name],name) In a multi user environment this is no longer reliable. If two workstations enter the same name on their input screens at the same time they will both pass the lookup test above. To ensure a unique entry you must re check if the value exists at the start of the procedure code and return to the input screen if the value has been taken since the field was filled. Declare variables x as number end For parts new record for parts alias checkit with name = input.name x = x + 1 next if x > 0 then beep Display Status "This part name already exists !" Delay 2000 Recall input screen end if copy all from input next When the line "For parts new record" is processed, the parts form is locked so no other workstation can add a record. If the name does not exist then the procedure adds the new record but if it does the operator is warned by the beep and status display and the procedure returns to the input screen without adding the new record. - 19 - ................................................................................